Graphviz Layouts

Graphviz layouts can be modified radically by rendering the graph with different Graphviz layouts.

The Layouts

By default, the grViz() function renders graphs with the standard dot layout. However, the neato, twopi, and circo layouts are selectable by setting the graph attribute layout equal to either neato, twopi, or circo in a Graphviz graph statement.

dot

By default, the grViz() function renders graphs using the standard dot layout. However, the neato, twopi, and circo layouts are selectable by supplying those names in a layout statement.

graph [layout = dot|neato|twopi|circo]

The dot layout flows the directed graph in the direction of rank (i.e., downstream nodes of the same rank are aligned). By default, the direction is from top to bottom (where the graph attribute rankdir is set to TB). The following examples will use the same Graphviz DOT code, differing only in the choice of layout. Here is the default dot output.

grViz("
digraph dot {

graph [layout = dot]

node [shape = circle,
      style = filled,
      color = grey,
      label = '']

node [fillcolor = red]
a

node [fillcolor = green]
b c d

node [fillcolor = orange]

edge [color = grey]
a -> {b c d}
b -> {e f g h i j}
c -> {k l m n o p}
d -> {q r s t u v}
}")

Note that in the previous example, rank 1 is the red node whereas ranks 2 and 3 are colored green and yellow, respectively. Alternatively, the rank direction can be set to left to right in a graph statement (rankdir = LR).

grViz("
digraph dot {

graph [layout = dot,
       rankdir = LR]

node [shape = circle,
      style = filled,
      color = grey,
      label = '']

node [fillcolor = red]
a

node [fillcolor = green]
b c d

node [fillcolor = orange]

edge [color = grey]
a -> {b c d}
b -> {e f g h i j}
c -> {k l m n o p}
d -> {q r s t u v}
}")

neato

The neato layout provides spring model layouts. This is a suitable layout if the graph is not too large (less than 100 nodes) and you don't know anything else about it. The neato layout attempts to minimize a global energy function, which is equivalent to statistical multi-dimensional scaling. Have a look at the previous graph, rendered with the neato layout:

grViz("
digraph neato {

graph [layout = neato]

node [shape = circle,
      style = filled,
      color = grey,
      label = '']

node [fillcolor = red]
a

node [fillcolor = green]
b c d

node [fillcolor = orange]

edge [color = grey]
a -> {b c d}
b -> {e f g h i j}
c -> {k l m n o p}
d -> {q r s t u v}
}")

Things do actually get interesting if there are lots of nodes. Here is an example of an undirected graph with 407 nodes amongst several ranks. Graph edges have varying lengths. (The code is not presented here as it is rather lenghty but it is available as a GitHub gist.)

The graph specification can have an entirely different layout with the neato layout if the graph attribute overlap is set to false instead of the default true value (GitHub gist). What occurs in this case is that node overlaps are removed by a Voronoi-based technique.

twopi

The twopi layout provides radial layouts. Nodes are placed on concentric circles depending their distance from a given root node. In the following example, that root node is the red one.

grViz("
digraph twopi {

graph [layout = twopi]

node [shape = circle,
      style = filled,
      color = grey,
      label = '']

node [fillcolor = red]
a

node [fillcolor = green]
b c d

node [fillcolor = orange]

edge [color = grey]
a -> {b c d}
b -> {e f g h i j}
c -> {k l m n o p}
d -> {q r s t u v}
}")

circo

With circo, a circular layout results. This is suitable for certain diagrams of multiple cyclic structures, such as certain telecommunications networks.

grViz("
digraph circo {

graph [layout = circo]

node [shape = circle,
      style = filled,
      color = grey,
      label = '']

node [fillcolor = red]
a

node [fillcolor = green]
b c d

node [fillcolor = orange]

edge [color = grey]
a -> {b c d}
b -> {e f g h i j}
c -> {k l m n o p}
d -> {q r s t u v}
}")

mermaid

The mermaid library is part of DiagrammeR. With it, you can describe graphs and sequence diagrams.

mermaid Basics

For mermaid diagrams, DiagrammeR uses the processing function called mermaid. What you pass into mermaid is a valid graph or sequence diagram specification. The specification can either be delivered to mermaid in the form of a string, a reference to a mermaid file (with a .mmd file extension), or as a text connection.

All of the code examples provided in later sections call the mermaid function in an R script and pass in a specification as a string. It is important to consider that strings in R cannot contain any unescaped double-quote characters. However, the mermaid function allows for single-quote characters in their place. As a further convenience, when a mermaid graph description is supplied as a file (e.g., 'mermaid-graph.mmd') or as a text connection, either format for quotes will be accepted.

In very recent builds of RStudio, the use of an external text file with the .mmd file extension can provide the advantage of syntax coloring and previewing in the RStudio Viewer pane after saving (if 'Preview on Save' is selected), or, by pressing the 'Preview' button on the Source pane.

Defining a mermaid Graph

The mermaid graph specification begins with a declaration of graph followed by the graph direction. The directions can be

• LR left to right
• RL right to left
• TB top to bottom
• BT bottom to top
• TD top down (same as TB)

Nodes can be given arbitrary ID values and those IDs are displayed as text within their respective boxes. Connections between nodes are denoted by:

• --> arrow connection
• --- line connection

Simply joining up a series of nodes in a left-to-right graph can be done in a few lines:

mermaid("
graph LR
  A-->B
  A-->C
  C-->E
  B-->D
  C-->D
  D-->F
  E-->F
")

The same result can be achieved in a more succinct manner with this R statement (using semicolons between statements in the mermaid diagram spec):

mermaid("graph LR; A-->B; A-->C; C-->E; B-->D; C-->D; D-->F; E-->F")

Alternatively, here is the result of using the statement graph TB in place of graph LR:

mermaid("
graph TB
  A-->B
  A-->C
  C-->E
  B-->D
  C-->D
  D-->F
  E-->F
")

Keep in mind that external .mmd files can also be called by the mermaid function. The file graph.mmd can contain the text of the diagram specification as follows:

graph LR
  A-->B
  A-->C
  C-->E
  B-->D
  C-->D
  D-->F
  E-->F

and be rendered through:

mermaid("graph.mmd")

Node Shape and Text

When assigning nodes, the default behavior is to assign the node IDs as text within the node objects. The addition of text inside node objects occurs through simultaneous assignment of both the node shape and the node label. The syntax for assigning text to a label is

[ID][opening brace][label][closing brace]

There the different types of patterns of opening and closing braces enclosing the label that change the shape of the node. Using [ and ] yields text in a rectangular node

mermaid("
graph LR
  A[node text]
")

Text placed in a node shaped as a rounded rectangle is done using ( and )

mermaid("
graph LR
  A(node text)
")

A circular node with text can be created by encapsulating the text with (( and ))

mermaid("
graph LR
  A((node text))
")

A rhombus node is made with { and }

mermaid("
graph LR
  A{node text}
")

Finally, there is a special type of shape which is asymmetric and resembles a flag. Only one representation is possible at this time, which is constructed with > and ]

mermaid("
graph LR
  A>node text]
")

Combining these node shapes together in a single graph, the following may be obtained

mermaid("
graph LR
A(Rounded)-->B[Rectangular]
B-->C{A Rhombus}
C-->D[Rectangle One]
C-->E[Rectangle Two]
")